Welcome back. Remember this URL that we used
before to find out what words rhyme with funny?
It's got the base part,
and then a question mark,
and then key equals value.
Well, how did we know what to put into that base part?
How did we know to use R-E-L_R-H-Y in order to ask for things that rhyme?
The answer is you use the documentation for the API.
So, let's take a look at the documentation of that API.
Then we'll see, they have lots of things in here.
So, in this documentation,
they tell us that the main URL is going to be api.datamuse.com,
and then they tell us some things that might go after that.
You might have /words?
something, or we'll see a little later on,
that there's some other things,
there's one other endpoint besides words.
We'll describe /words as being what endpoint,
and then the things after the question mark as being query parameters.
So, you can ask for ml,
and give a value ringing in the ears.
So, in their documentation, they tell you,
if you want to find out words with a meaning that's similar to ringing in the ears,
you would give the query over on the right-hand side.
We can scroll down and see some other things that you can do,
lots of opportunities, lots of different things you can do,
and here's that rel_rhy that I found.
That's for words that rhyme with forgetful.
Now, they've started by giving us a bunch of examples,
but then, down below,
they'll give you even more detail.
So, they're saying, you can access most things at datamuse.com/words.
So, that's going to end up being our base URL.
Then we have to figure out,
what are we going to put into that params dictionary?
We can use the examples above,
or we can try to look at some of the things
below that are giving more detailed information.
So, we can have the key be ml,
we could have a key sl for sounds like,
or there's a whole set of R-E-L_ things.
There's R-E-L_J-J-A or R-E-L_T-R-G,
or R-E-L_R-H-Y for rhymes with.
So, that's how I figured out what some of
the possible keys could be in my params dictionary.
Then for the value,
I really got it from my examples where I said, "Oh,
well the value is just the word that I'm trying to pass as an input,
I'm trying to get things that rhyme with forgetful or things that rhyme with funny."
So, that's telling me what kind of queries I can give to this REST API,
and at the bottom they'll tell me a little bit more about interpreting the results.
So, I've passed over the other endpoint /sug,
and I found something about what the responses will look like.
It's going to be a list,
that's what the square brackets tell me,
and they tell me it's always going to be
in the JSON format which you've been seeing already,
and it's a list of dictionaries.
Each dictionary is telling us information about one of
the words that is related to our query.
If our query was four words that rhyme with funny,
then we would get each word that is
a good rhyme for funny would have one dictionary in this list.
So, this is a relatively simple API,
and the documentation is pretty clear.
You can figure out pretty well, how to use it.
Another thing I want to show you with this API is just a nice practice
if know you're going to make a bunch of calls to
this API to get a bunch of rhyming words,
maybe you're using this as an aid to your next rap hit,
you might make a lot of calls to get_rhymes.
So, I've defined a little function here that I can call multiple times.
So, I can call get_rhymes on a word,
and I'll get back a list of some other words.
So, with funny, I'm getting back three things,
and I can get_rhymes on something else.
I want to get_rhymes with dash,
I get cache, flash, and crash.
Now, how did I implement this get_rhymes?
Well, get_rhymes is going to take as an input a word like funny, or dash.
So, that's going to be bound to my word parameter,
and it's going to return a list of three rhyming words.
But you saw that what we actually get back is not a list of words,
it's a list of dictionaries with information.
Each dictionary has information about one rhyming word.
So, the base URL is always the same,
I'm going to create a blank parameters dictionary.
Then I'm going to fill in rel_rhy should equal word,
and max should be three.
We were asking it to only give us three results back.
Then I call requests.get passing in that params dictionary.
I get a response object.
I turn that into a Python object by calling the JSON method on it,
and now, I'm going to use a list comprehension which you learned about recently.
We're iterating through each of the list of dictionaries.
For each of those dictionaries,
we're just extracting the word.
So, that produces a list like this,
and then I'm just returning it.
I just noticed that on line 13,
I have another return statement where it's returning something different,
but of course, once we execute the return on line 12,
we won't ever do line 13.
That's left over from a previous version I was
trying to do of this where instead of extracting just the words,
I was returning the whole dictionaries.
In fact, it might be instructive to look at that.
Let's comment out line 12,
and see what happens if we return the dictionaries rather than
extracting just the words from those dictionaries.
So, now we get a list of the three dictionaries.
Instead of just getting money, honey, and sunny,
we're getting this whole dictionary instead of just the word money.
So, this is the kind of thing that's pretty helpful if you
know that you're going to do the same thing,
make a bunch of requests to the same API,
just passing a little different parameter each time,
you might want to make a little function out of it like I did
here on lines four through 13.
That's an introduction to reading the documentation for REST API,
and also to making a function to repeatedly make similar kinds
of requests to a single API. We'll see you next time.